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1.  INTRODUCTION 


/ 


In  heterogeneous  computing  environments,  with  processors  of  diverse  capabilities  and 
resources,  it  is  often  beneficial  to  distribute  an  application  across  several  platforms.  An 
application  might  take  advantage  of  the  computational  power  of  one  machine,  data  storage  and 
retrieval  of  another,  and  the  graphical  prowess  of  a  third.  Practical  considerations  such  as 
machine  load,  availability,  and  physical  connection  often  are  just  as  important  when  choosing 
platforms. 

It  becomes  necessary  to  have  a  portable  method  for  transferring  data  between  processes 
executing  on  separate  machines  that  may  be  of  different  architectures.  Remote  data  Transfer 
(RdT)  provides  a  layer  of  utilities,  written  in  the  “C"  programming  ianguage,  that  enable  processes 
to  exchange  arbitrary  data  structures  without  dealing  with  many  of  the  specifics  of  the  actual 
transfer.  RdT  handles  the  possible  incompatibilities  of  internal  data  representation  between 
different  architectures  as  well  as  the  mechanics  of  communicating  that  data. 

RdT  is  based  on  the  Client-Server  model.  A  Server  makes  itself  available  to  perform  some 
service  on  behalf  of  a  Client.  The  Server  may  either  wait  on  incoming  requests  or  periodically 
check  for  incoming  requests  while  performing  some  other  function.  The  Client  issues  a  request 
then  waits  for  either  an  acknowledgement  that  the  request  has  been  received  or  the  service 
performed. 

RdT  consists  of  three  layers;  Data  Transfer,  Message  Passing,  and  Command  and 
Response.  The  Data  Transfer  Layer  defines  the  basic  data  types  that  can  be  exchanged  and 
handles  the  conversion  and  passing  of  the  data.  The  Message  Passing  Layer  handles  the 
registration  of  services,  the  oelivery  and  notification  of  requests,  and  the  return  of  responses.  The 
Command  and  Response  Layer  constructs  messages  from  an  independent  Command  structure 
and  disassembles  the  response  into  an  independent  Response  structure. 

The  Command  and  Response  Layer  defines  two  packages  of  information:  a 
COMMAND_PACKET  and  a  RETURN  PACKET.  These  packages  are  passed  to  the  Message 
Passing  Layer  which  repacks  them  into  structures  known  as  RT_VARs.  Then,  using  Remote 
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Client 


Server 


When  interfacing  with  the  Command  and  Response  Layer,  an  application  is  spared  the  details 
of  the  data  transfer.  The  Command  and  Response  interface  can  be  used  locally  or  between 
remote  processes. 


Client  Server 


Figure  2.  RdT  Lavers  and  Packages. 

RdT  has  been  tested  on  the  following  architectures: 

•  Sun  3 

•  Sun  4 

•  Vax  (Ultrix) 

•  Cray  X-MP 

•  QoukJ  Powemode 

•  Silicon  Graphics 

•  Ailiant 

•  Convex 

RdT  should  be  portable  to  most  UNIX  platforms.  See  appendix  for  user-callable  RdT  routines. 
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2.  DATA  TRANSFER  LAYER 


At  the  lowest  layer  of  RdT,  data  is  transferred  between  processes  using  the  XDR  format 
developed  by  Sun  Microsystems.  The  XDR  format  specifies  the  bit  and  byte  order  of  certain  data 
types  so  that  machines  that  have  different  internal  representations  of  data  can  exchange 
information.  To  transfer  data,  RdT  uses  the  following  basic  XDR  data  types;  unsigned  char  (an 
8-bit  unsigned  character),  short  (a  16-bit  signed  integer),  long  (a  32-bit  signed  integer),  float 
(a  32-bit  signed  floating  point  number),  and  double  (a  64-bit  signed  floating  point  number). 

Using  these  basic  data  types,  two  additional  types  are  added  to  the  Data  Transfer  Layer  of 
RdT.  The  first  is  a  COMPLEX  data  type  that  contains  two  floats  defining  the  real  and  imaginary 
parts  of  a  complex  number.  The  other  data  type  is  a  STRING  type  that  contains  a  NULL 
terminated  character  string  and  a  short  integer  that  defines  its  length. 

There  are  XDR  routines  for  each  of  these  basic  data  types  that  encode  and  decode  each 
element.  These  routines  can  convert  the  machine  specific  internal  representation  of  these  basic 
elements  to  the  XDR  representation  and  from  XDR  to  the  internal  format.  When  decoding 
information,  these  routines  must  allocate  memory  for  the  incoming  data  if  the  Server  is  decoding 
a  command  or  if  the  Client  is  decoding  a  response. 

These  basic  RdT  data  types  are  packaged  into  a  structure  called  an  RT_VAR.  An  RT_VAR 
may  contain  a  single  data  element,  or  an  array  of  these  basic  elements.  Information  in  the 
RT_VAR  describes  the  type  of  the  individual  element  and  the  dimensions  of  the  variable.  For 
example,  a  1 0  by  20  array  of  floats  would  contain  information  defining  the  basic  type  as  a  float, 
define  the  number  of  dimensions  as  2,  and  contain  an  array  of  length  2  that  defines  the  length 
of  each  dimension. 

The  RT_VAR  structure  is  defined  as: 
typedef  struct  { 

unsigned  char  direction;  r  Server  or  Client  owned  V 

unsigned  char  type;  /*  Basic  data  type  V 

unsigned  char  element_size;  /*  Byte  length  of  each  element  7 
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unsigned  char  n_dim;  /*  Length  of  dimension  array  V 

long  dim[MAX_ARRAY_DIM];  T  Dimensions  */ 

RT_TYPES  value;  r  Union  of  basic  data  types  or  7 

}  RT_VAR  r  pointer  to  array  7 

When  receiving  information,  memory  space  must  be  allocated  to  hold  the  RT_VAR  and  its 
data.  The  element_size  and  dimension  information  are  used  to  determine  the  space  requirements 
while  the  direction  information  indicates  whether  that  space  can  be  freed  at  a  later  time.  For 
example,  if  a  server  process  is  receiving  an  array  of  floats  and  returns  the  sum,  it  must  first 
allocate  space  for  the  original  array.  Once  the  sum  is  computed,  however,  the  space  can  be 
freed. 

These  RT_VARS  can  further  be  packaged  into  a  STRUCTURE.  A  STRUCTURE  simply 
contains  the  number  of  RT_VARS  and  an  RT_VAR  array. 

typedef  struct  { 

unsigned  long  n_elements; 

RT_VAR  *element[MAX_STRUCT_ELEMENTS]; 

} STRUCTURE; 

By  using  these  data  types,  processes  can  pass  information  as  arguments  and  results.  The 
data  can  be  single  elements,  arrays,  or  a  combination  of  the  two,  I.e.,  a  STRUCTURE.  The  Data 
Transfer  Layer  takes  care  of  unpacking  and  building  these  variable  types  in  addition  to  managing 
the  memory  requirements.  The  valid  types  for  an  RT_VAR  are: 


#define  TYPE_UNDEF  0 

#define  TYPE_BYTE  1 

#define  TYPE_SHORT  2 

#define  TYPE_LONG  3 

#define  TYPE_FLOAT  4 

#define  TYPE_DOUBLE  5 

#define  TYPE  COMPLEX  6 
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#define  TYPE_STRING  7 

#deflne  TYPE_STRUCT  8 

If  the  RT_VAR  contains  more  than  one  basic  element,  it  is  ORed  with: 

#define  TYPE_ARRAY  0x80  /*  Compound  type  */ 

An  array  of  floats  would  be  defined  as: 
rt_var.type  =  TYPE.FLOAT  |  TYPE_ARRAY 

r/PE_STRUCT  would  contain  RT_VARS  of  type  0  through  7  or  arrays  of  those  types.  Currently, 
TYPE_STRUCT  cannot  contain  RT_VARS  of  TYPE_STRUCT  (nested  structures)  and  array  of 
structures  are  invalid. 


Two  routines  automate  the  building  of  RT_VARS:  rtu_make_yar  and  rtujmake_structure. 


Rdt  Data  Types 

RT_VAR^Element 


Element 


‘Array  of  Elements 
Structure  of  Elements  and  Arrays 
Byte 

16  bit  integer 

32  bit  integer 

32  bit  float 
64  bit  float 

Complex  (floats) 

String  (integer  and  bytes) 

Figure  3.  RdT  Data  Types. 
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int 

rtu_make_var(rt_var _ptr,  type,  length,  data) 

RT_VAR  *rt_var_ptr; 

unsigned  char  type; 

unsigned  long  length; 

char  *data; 

This  routine  will  build  the  RT_VAR  pointed  to  by  rt_var_ptr  using  the  data  pointed  to  by  data. 
Notice  that  data  must  always  be  a  pointer.  The  rtu_make_var  on\'^  builds  single  dimension  arrays 
or  basic  element  variables.  To  build  multi-dimensional  arrays,  the  ndim  and  dimension  RT_VAR 
structure  elements  must  be  modified  directly. 

To  build  a  STRUCTURE  variable,  the  call  ttujnakejs^ucture  is  used.  This  routine  uses  a 
variable  argument  list  so  the  call  would  look  like: 

rt_var_ptr  =  (RT_VAR  •)rtu_make_structure{c_structure_pointer, 

type,  length, 
type,  length. 


type,  length, 
type,  length, 

0); 

where  type  is  an  unsigned  char  and  length  is  an  unsigned  long.  So  to  pass  the  "C  structure: 
struct  { 

long  arrayjength;  /*  Length  of  array  */ 

float  *float_array;  r  Array  of  length  "arrayjength" "/ 

}  my_struct; 
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The  call  would  be: 


rt_var_ptr  *  (RT_VAR  *)rtu_make_structure(&my_struct, 

TYPE_LONG.  1. 

TYPE_FLOAT  |  TYPE_ARRAY,  mystruct.arrayjength, 

0): 

3.  MESSAGE  PASSING  LAYER 

Once  the  data  has  been  described,  it  is  passed  to  the  next  layer  of  RdT— the  Message 
Passing  Layer.  This  layer  is  based  on  the  Remote  Procedure  Call  protocol  also  developed  by 
Sun  Microsystems.  A  Server  process  registers  some  service  and  listens  for  a  request  arrive. 
When  one  does  arrive,  the  data  is  decoded  from  the  RT_VARs  and  passed  to  some  service  in 
the  Server.  The  results  of  this  service  are  then  returned  as  an  RT_VAR. 

On  the  Ciient  side,  a  request  is  made  for  a  service  to  some  remote  host  passing  RT_\/ARs 
as  arguments.  The  Client  makes  the  request,  then  waits  for  a  response.  If  a  response  is  not 
received  in  the  user  defined  time  limit,  the  request  times  out  and  a  TYPE_ERROR  is  returned. 
If  the  Server  dies  or  is  unabie  to  decode  the  arguments,  the  Client  is  aiso  notified. 

Data  transfer  is  accomplished  using  Transmission  Control  Protocol  (TCP),  the  virtual  circuit 
protocol  of  the  Internet  protocol  family.  TCP  is  used  instead  of  User  Datagram  Protocol  (UDP) 
since  UDP  is  unreiiable  and  transfers  are  iimited  to  8  kB  in  length.  TCP  is  layered  above  the 
Internet  Protocol  (IP)  and  provides  reiiabie,  fiow-controiled.  in  order,  two-way  transmission  of  data. 
The  Server  and  Client  are  connected  to  TCP  sockets  and  transfer  their  XDR  data  by  reading  and 
writing  to  these  sockets. 

3.1  The  Server.  A  Server  process  makes  a  cail  to  rtu_reg  to  register  a  service.  This  call 
takes  a  service  number  as  an  argument. 

int 

rtu_reg(service_number) 
int  service_number: 
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Typical  RdT  Server 

Register  Service  ___ 

I 


1 


Wait  for  Request  Check  for  Request 


t  i 

Retreive  Parameters 

♦ 

Perform  Service 

y 

Respond  to  Client 


;  y  Do  Other  Processing 
ick  for  Request  ^ 
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Figure  4.  Typical  RdT  Server. 


A  RPC  service  is  made  unique  by  a  PROGRAM  and  VERSION  number.  All  RdT  services  use 
the  same  PROGRAM  number.  They  make  themselves  unique  by  adding  this  servic0_number\o 
the  RPC  VERSION  number.  When  a  request  for  a  particular  RPC  service  is  received,  it  is 
directed  to  the  process  that  has  previously  registered  that  PROGRAM  and  (VERSION  + 
service_numbei)  pair. 


The  service  number  is  used  to  distinguish  this  service  from  other  services  on  the  machine. 
It  is  an  arbitrary  number  that  the  Client  will  pass  to  its  routines  as  well.  In  this  way,  multiple 
Servers  can  exist  on  the  same  machine  and  receive  only  the  calls  that  are  intended  for  them. 
The  RPC  protocol  manages  the  routing  of  these  requests  to  the  proper  Server. 

The  routine  rtu_reg  returns  once  the  service  has  been  registered.  To  check  if  there  are  any 
incoming  requests,  the  Server  makes  calls  to  rtu _poll.  This  routine  can  be  instructed  to  check 
for  requests  and  return  or  to  block  and  wait  for  an  incoming  request. 
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int 

rtu_poll(user_data,  procedure,  blockjime) 
char  **user_data,  “procedure: 
int  block_time; 

The  userjdata,  when  returned,  will  point  to  a  string  that  contains  some  user-defined  data. 
This  user-defined  data  is  typically  some  application  level  authorization  (a  password)  but  can  be 
used  in  any  manner  the  application  sees  fit. 

The  procedure  will  also  point  to  a  string  that  was  passed  by  the  Client.  This  information  is 
typically  the  name  of  the  particular  function  within  a  Server  that  is  requested.  For  example,  one 
server  might  contain  the  functions  "FFT,"  "SUM,"  and  “PLOT."  A  Client  would  request  a  particular 
function  from  the  Server  by  specifying  the  name  of  the  function.  Again,  this  is  the  intended  use, 
but  the  actual  use  is  determined  by  the  application. 

Strings  are  used  for  the  userjdata  and  procedure  to  facilitate  the  development  of  simple 
Servers  that  call  some  pre-existing  package.  The  userjdata  can  be  an  access  authorization, 
while  the  procedure  can  be  a  command  line.  In  this  scenario,  RT_VARs  would  not  have  to  be 
built  or  managed. 

The  b!ock_time  determines  whether  rtu joo// blocks  until  a  request  is  received  or  returns  after 
checking  for  a  request.  If  blockjime  is  negative,  rfu _po// blocks.  Otherwise,  the  value  blockjime 
is  used  as  the  amount  of  seconds  to  wait  for  an  incoming  request.  If  blockjime  is  equal  to  0, 
rtu j)Oll  checks  for  a  request  and  returns.  In  all  cases,  rtu jjoll  returns  a  1  if  there  is  a  request 
or  0  if  there  is  not 

Once  rtu jxjH  returns  with  a  request,  the  Server  retrieves  the  parameters  with  a  call  to 
rtu _get j)ar. 

char  • 

rtu_getj5ar(parameter_number,  expected_type) 
int  parameter_number; 
unsigned  char  expected_type; 
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Parameters  are  numbered  starting  with  zero.  The  total  number  of  parameters  is  defined  by 
RT_NUMARGS.  So  the  first  parameter  would  be  retreived  by  "rtu_get_par(0,  param_type)"  and 
the  last  would  be  retrieved  by  "rtu_getjDar(RT_NUMARGS  - 1 ,  param_type)." 

If  the  type  of  the  passed  in  parameter  matches  the  expected  type,  a  pointer  is  returned  that 
points  to  that  data.  For  example,  if  the  first  expected  parameter  to  a  service  is  a  float,  the  request 
would  be: 

float  *first_param; 

firstjjaram  «  (float  *)rtu_get _par(0,  TYPE_FLOAT); 

/*  For  a  single  float  parameter  */ 
r  or  V 

first jDaram  =  (float  *)rtu_get_par(0,  TYPE_FLOAT  I  TYPE_ARRAY); 

/*  For  an  array  of  floats  V 

If  the  type  does  not  match,  or  no  such  parameter  exists  (e.g.,  asking  for  parameter  10  when 
only  9  were  passed),  a  NULL  pointer  is  returned.  While  It  would  be  valid  to  request  the  value 
directly: 

float  first_value: 

first_value  =  '(float  *)rtu_get_par(0,  TYPE_FLOAT); 

this  is  not  recommended  since  rtu jget _par  can  return  a  NULL,  causing  the  program  to  fail.  It  is 
always  wise  to  make  sure  that  rtujget _par  returned  a  valid  parameter. 

The  Server  must  always  reply  to  the  Client.  This  reply  can  be  after  the  requested  service  has 
been  performed  (the  usual  case)  or  at  some  other  point  in  time.  Since  the  Client  is  blocked  when 
it  makes  a  call  to  the  Sen/er,  some  returned  value  must  be  received  before  it  can  continue.  The 
Server  responds  to  the  Client  with  "rtu_reply." 
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int 

rtu_reply(service_number,  reply_method,  reply) 
int  service_number,  reply_methocl; 

RT_VAR  ‘reply; 

Service  number  is  the  same  servicejnumber  used  in  the  cali  to  rtu_reg.  If  reply_method  is 
1 ,  oniy  the  repiy  pointed  to  by  reply  is  returned  to  the  Client.  If  reply_method  is  0.  then  all  the 
parameters  that  were  passed  to  the  Server  are  returned  to  the  Client.  In  this  manner,  the  Server 
could  modify  some  or  all  of  the  parameters  and  pass  back  the  results  in  the  parameters 
themselves.  For  large  arrays,  this  is  sometimes  necessary.  Clearly,  returning  the  parameters 
to  the  Client  requires  more  communication,  in  any  case,  the  Server  must  always  reply  to  the 
Client  with  some  value,  even  if  that  value  is  oniy  a  single  byte.  There  are  routines  that  make 
responses  easy  by  building  the  RT_VAR  and  responding.  One  such  routine  is  rtu_smpl_reply. 

int 

rtu_smpl_repiy(type,  length,  data) 
unsigned  char  type;  /*  RT_VAR  type  */ 

unsigned  long  length;  /*  1  or  length  of  array  V 

char  ‘data;  r  Always  a  pointer  V 

When  the  Server  is  receiving  parameters,  it  must  allocate  memory  to  store  them.  RdT  keeps 
a  list  of  ail  the  memory  it  has  allocated.  This  iist  is  freed  on  the  next  reply.  This  means  that  a 
Server  must  copy  parameters  which  it  wishes  to  retain  before  it  makes  a  reply  to  the  Client. 

3.2  The  Client.  The  Client  requests  a  service  from  the  server  by  using  rtu_c^l. 

RT_VAR  ‘ 

rtu_cali(rt_argc,  rt_argv,  hostname,  servicejd,  procedure,  used_data,  timeout) 


int 

rt_argc; 

RT_VAR 

‘rt_argvO; 

int 

servicejd,  timeout; 

char 

‘procedure,  ‘user_data,  ‘hostname; 
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The  rt_argc  defines  the  number  of  RT_VARS  that  are  contained  in  the  array  rt_argv.  The 
hostname  string  contains  the  name  of  the  machine  where  the  service  with  servicejd  is  located. 
The  userjdata  and  procedure  strings  are  passed  to  the  Server  as  described  previously. 

The  timeout  is  the  number  of  seconds  to  allow  for  a  response.  If  a  response  is  not  received 
In  the  allotted  time,  rft/_ca//  returns  an  error.  Errors  are  returned  from  rtu_call  by  the  type  of  the 
returned  value  being  set  to  TYPE_ERROR  (0  x  FF). 

As  with  the  Server,  incoming  data  (the  response)  is  stored  in  memory  allocated  by  RdT.  This 
memory  is  freed  on  the  next  call  to  rtu_calL  So  the  Client  must  copy  this  response  before  the 
next  call  to  rtu_call  if  it  wishes  to  retain  the  information. 

The  rtu_call  blocks  until  a  response  is  received  or  an  error  occurs.  To  implement  non- 
blocking  communication,  the  Server  and  Client  must  cooperate.  The  Client  would  first  register 
a  service  but  not  issue  a  rtu _poll.  Next,  the  Client  would  make  a  call  with  rtu_call,  and  the 
Server  would  respond  with  a  status  value  indicating  that  it  received  the  Client’s  parameters.  The 
Client  could  then  call  rtu jpoH  to  check  on  the  actual  return  value  to  its  request.  The  Server 
would  make  the  actual  response  with  rtujcaH  In  this  situation,  both  sides  are  implementing 
Servers  and  Clients. 

4.  COMMAND  AND  RESPONSE  LAYER 

The  Command  and  Response  Layer  (CRL)  is  implemented  above  the  message  passing  layer 
of  RdT  and  based  on  three  basic  structures: 


typedef  struct  { 

unsigned  char 

int 

char 

}  PARAM_LIST: 

type; 

num_value; 

'value; 

/*  Same  as  basic  RdT  types  */ 

r  Number  of  elements  in  array  7 

r  Pointer  to  data  7 

typedef  struct  { 

int 

opcode; 

r  Function  request  */ 

13 


int  num_param;  /*  Number  of  parameters  7 

PARAM_LIST  *param;  /*  Parameter  list  7 

}  COMMAND_PACKET 


typedef  struct  { 

int  status; 

char  ‘explain; 

int  num_retum; 

PARAM_LIST  ‘params; 

}  RETURN_PACKET; 


r  Status  of  operation  7 
r  Error  message  7 
r  Number  of  elements  returned  7 
r  Return  params  7 


CRL  is  designed  to  implement  the  Client-Server  model  through  peer-to-peer  communications 
above  the  message  passing  layer.  A  Client  constructs  a  COMMAND_PACKET,  passes  it  to  the 
Server,  and  is  returned  a  RETURN_PACKET.  The  actual  transport  of  the  COMMAND_PACKET 
and  RETURN_PACKET  is  transparent  to  the  Client  and  Server.  CRL  could  be  implemented  as 
shared  memory,  subroutine  calls,  or,  as  in  this  case,  the  RdT  message  layer. 

The  PARAM_LIST  is  basically  a  stripped-down  version  of  an  RT_VAR.  It  only  contains  the 
type  of  the  data  and  the  number  of  elements.  The  type  is  the  same  as  those  used  in  an 
RT  VAR. 


A  COMMAND_PACKET  contains  an  opcode  whidi  performs  the  same  function  as  procedure 
in  the  rtu_call  routine.  This  opcode,  however,  is  easier  to  handle  in  a  "C"  switch  statement  of  the 
Server  and  is  contained  within  the  packet  itself.  The  num _param  element  of  the 
COMMAND_PACKET  structure  defines  the  length  of  the  parameter  list  param. 

The  Client  passes  a  COMMAND_PACKET  into  CRL  and  is  eventually  returned  a 
RETURN_PACKET.  A  nonnegative  status  indicates  successful  completion  of  the  requested 
service  while  a  negative  status  indicates  an  error.  Errors  are  explained  in  the  NULL  terminated 
expfa/n  element  of  the  packet  The  data  (usually  a  "C  structure)  points  to  the  data  that  was 
returned  from  the  Server. 
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The  RETURN_PACKET,  which  is  built  by  the  Server,  is  unpacked  and  the  data  returned  to 
the  Client  The  CRL  handles  packing  and  unpacking  the  data  in  the  RETURN_PACKET. 

CRL  makes  it  easy  for  a  Client  and  Server  to  exchange  arbitrary  data  structures  without 
concern  for  the  actual  delivery  mechanism.  For  example,  a  Client  wants  to  pass  the  following 
structure: 

struct  { 

long  arrayjength;  r  Length  of  array  7 

float  *float_array;  /*  Array  of  length  "arrayjength"  */ 

}  my_struct; 

The  Client  first  calls  the  macro  SET_PARAM  to  put  the  structure  my_struct  into  a 
COMMAND_PACKET. 

COMMAND_PACKET  command; 

r  SELECT_COMMAND  allocates  space  for  the  parameters  and  places  some  7 
r  information  like  opcode  and  number  of  parameters,  into  the  */ 
r  COMMAND_PACKET.  Usage:  7 

r  SELECT_COMMAND(commandj3acket,  OPCODE,  number_of_parameters)  7 
SELECT_COMMAND(command,  999, 1); 

r  SET_PARAM(command_packet,  which_param,  type,  num_elements,  data)  7 
SET_PARAM(command,  0,  TYPE_STRUCT,  1,  rtu_make_structure(&my_struct, 

TYPE.LONG,  1, 

TYPE_FLOAT  |  TYPE_ARRAY,  mystruct.arrayjength, 

0); 

SET_PARAM  builds  a  COMMAND_PACKET  for  the  Command  and  Response  Layer.  The 
opcode  is  an  arbitrary  number,  agreed  upon  by  the  Client  and  Server  to  request  a  particular 
function  within  the  Server,  In  response  to  the  request,  the  Client  expects  some  predefined  data 
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structure.  For  example,  an  opcode  999  requested  the  Server  to  sum  and  reverse  the  array  in 
my_struct.  The  Server  would  return  some  structure  RETVAL  defined  as: 

typedef  struct  { 

float  sum;  T  Sum  of  passed  array  */ 

float  ‘reverse;  /*  Reversed  array  V 

}  RETVAL; 

RETVAL  *retum_val; 

The  actual  call  that  the  Client  would  make  to  the  Sen/er  would  be: 

retum_val  =  (RETVAL  *)rtu_send_cmd(hostname,  service_number,  &command); 

The  routine  rtujsend_cmd  calls  the  Server  on  machine  hosbiame  and  passes  it  the 
COMMAND.PACKET  (which,  incidently.  it  passes  as  a  RT_VAR  of  TYPE_STRUCT).  The  Server 
accesses  the  COMMAND_PACKET.  calculates  the  sum  of  the  array,  reverses  the  array  into  a 
return  array,  and  finally  responds  with  a  RETURN_PACKET.  The  data  element  of  this  packet  is 
returned  to  the  Client  from  rtujsendjcmd.  If  an  error  occurred.  rtu_send_cmd  returns  a  NULL 
pointer.  The  Client  does  not  directly  unpack  the  RETURN_PACKET. 

The  Server  uses  rtu _get_cmd\o  wait  for  an  incoming  COMMAND_PACKET.  For  example: 

COMMAND_PACKET  ‘command; 

command  *  (COMMAND_PACKET  ‘)rtujget_cmd(service_number); 

Where  service__number  is  the  same  as  service_number  in  the  call  to  rtu_reg.  In 
implementations  other  than  a  RdT  message  passing  layer,  this  service  number  could  be  some 
other  relevant  identification  such  as  a  shared  memory  segment. 

The  Server  can  now  directly  access  the  parameters  in  the  COMMAND_PACKET.  For 
example,  if  the  first  expected  parameter  were  "mystruct."  the  Server  would  access  it  with: 
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mystruct j3tr  =  (MYSTRUCT  *)command->param[0].value: 


In  this  example,  the  routine  rtu_get_cmcl  has  unpacked  the  incoming  RT_VAR  of 
TYPE_STRUCT  into  a  COMMAND_PACKET.  The  Server  accesses  each  parameter  directly. 
Once  the  service  has  been  performed,  the  Server  constructs  a  RETURN_PACKET  and  returns 
it  to  the  Client  with  a  call  to  rtu_retum: 

rtu_retum(packet) 

RETURN_PACKET  'packet; 

The  RETURN_PACKET  is  returned  to  the  Client,  and  the  routine  rt_send_cmd  returns  a 
pointer  to  this  data  back  to  the  Client. 

The  CRL  provides  a  mechanism  to  implement  the  Client-Server  model  which  insulates  the 
upper  level  application  from  the  actual  message  passing.  In  this  way,  a  Client-Server  application 
can  focus  on  issues  concerning  the  application  with  minimal  concern  for  the  actual  communication 
mechanism. 

5.  AN  APPLICATION 


Many  Computational  Fluid  Dynamics  (CFD)  codes  that  execute  on  supercomputers  deal  with 
enormous  amounts  of  data.  These  codes  typically  use  a  grid  or  set  of  grids  to  define  discrete 
points  in  some  computational  domain  and  calculate  different  properties  for  these  grids  in  small 
timesteps.  These  grids,  however,  can  contain  millions  of  grid  points.  The  solutions  can  contain 
many  different  values  for  each  grid  point.  There  is  simply  too  much  data  for  a  smaller  machine 
to  handle  all  at  once. 

It  is  desirable,  however,  to  visualize  the  results  of  these  codes  on  a  much  smaller  machine 
such  as  a  workstation.  This  not  only  frees  the  supercomputer  for  computation  but  provides  many 
more  options  for  viewing  the  data  since  there  are  a  variety  of  visualization  packages  that  run  on 
workstations. 
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This  use  of  workstations  is  only  viable,  however,  if  the  grid  can  be  accessed  in  pieces.  By 
visualizing  the  grid  and  solution  in  stages,  the  entire  problem  can  be  viewed  by  assembling  the 
stages  at  the  end. 

To  accomplish  this  grid  slicing,  the  Client-Server  model  is  a  good  choice.  A  Server  process 
on  the  supercomputer  responds  to  requests  for  a  specific  slice  of  the  entire  grid.  The  Client 
process  on  the  workstations  makes  requests  for  manageable  pieces  of  the  grid.  In  addition,  if 
these  grids  on  the  supercomputer  are  stored  in  files,  they  can  remain  in  the  host  binary  format 
and  do  not  require  the  conversion  and  transmission  to  the  lower  end  machine. 

RTU_SERVER  is  an  example  of  just  such  a  grid  server,  it  is  implemented  on  the  CRL  of  RdT 
and  supports  opcodes  that  include:  open  file,  close  file,  read  grid  (slice),  read  solution  (slice),  and 
check  speed.  The  Client  receives  information  from  the  Server  in  a  predetermined  data  structure, 
GRIDJNFO_STRUCT,  that  contains  grid  size  information  as  well  as  the  data. 

The  Server  waits  for  an  incoming  COMMAND_PACKET.  The  Client  first  requests  the  Server 
to  open  a  file  that  is  in  one  of  three  formats:  binary,  formatted  ASCII,  or  FORTRAN  77 
unformatted.  The  Server  opens  the  file  and  returns  to  the  Client  the  grid  size  information 
involved.  The  Client  can  then  request  certain  sections  of  grid  (or  solution)  and  eventually  request 
that  the  file  be  closed. 

For  example,  suppose  we  were  dealing  witfi  a  grid  big_grid(i,  j,  k)  where  i  =  64,  ]  =  32,  and 
k  »  64,  and  is  stored  in  a  FORTRAN  77  unformatted  file  called  big_grid.dat.  To  access  this  grid, 
the  Client  makes  the  call: 

r  SELECT_COMMAND(command_packet,  OPCODE,  number_of_parameters)  V 
SELECT_COMMAND(command.  RTU_OPEN,  2); 
r  SET_PARAM(command _packet,  parameter_number,  type,  length,  data)  V 
filename  » "blgjrid.dat": 

SET_PARAM(command,  0,  TYPE_STRING,  1,  filename): 
file.type  «  F77_UNFORMATTED; 

SET_PARAM(command,  1,  TYPE_LONG,  1,  &file_type): 
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if((gricl_info  =  (GRID_INFO_STRUCT  *)rtu_sencl_cmd(hostname, 
service_number,  &command))  ==  NULL){ 

fprintf(stderr,  "Unable  to  open  file  %s  on  %s\n,"  filename,  hostname); 
exit(1); 

} 

The  Client  then  selects  which  slice  of  the  grid  is  desired,  stores  that  information  back  in  the 
gridjnfo  structure,  and  sends  the  structure  as  a  parameter  to  the  "read  grid"  function  of  the 
Server: 

gridJnfo->which_grid  *  0;  /"A  grid  file  can  contain  multiple  grids  */ 

gridJnfo->num_planes  =  2; 

gridJnfo->which_plane  =  KPLANE; 

grid_info->planes[0]  =  2; 

grld_info->planes[1]  =  16; 

SELECT_COMMAND(command,  RTU_READ_GRID.  1); 

SET_PARAM(command,  0,  TYPE_STRUCT,  1. 

rtu_make_structure(gridJnfo,  GRIDJNFO_DESC(gridJnfo))); 
r  GRID_INFO_DESC()  is  a  macro  that  constructs  the  proper  */ 

/*  parameter  list  for  rtu_make_structure()  from  the  structure  */ 

/*  in  gridjnfo.  V 

if((grid  =  (GRID_DATA_STRUCT  •)rtu_send_cmd(hostname, 
sen/ice_number,  &command))  =  NULL){ 

fprintf(stderr,  "Error  reading  grid  from  %s\n",  hostname); 
exit(1); 

} 

In  similar  manner,  the  Client  reads  the  same  slices  of  the  solution  file  from  the  Sen/er.  By 
requesting  the  grid  and  solution  in  manageable  pieces,  the  low  end  machine  is  able  to  deal  with 
a  huge  amount  of  data.  In  addition,  there  is  no  need  to  convert  the  FORTRAN  77  unformatted 
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files  to  another  format  and/or  transfer  them  to  the  low  end  machine  with  possibly  modest  disk 
resource. 

This  grid  server  (Figure  5)  is  currently  used  In  a  distributed  visualization  environment  The 
computation  on  the  supercomputer  can  proceed  in  parallel  with  the  visuedization  which  has  been 
off-loaded  to  another  machine.  The  visualization  platform  can  be  chosen  not  only  based  on 
processing  power  or  graphics  hardware  but  on  practical  considerations  such  as  machine  load 
physical  connection  and  availability. 


RTU_SERVER  grid  sUcer 


Server 
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32 
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Client 


Kplane 


Figure  5.  RTU_Server  Grid  Slicer. 
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6.  CONCLUSIONS 


RdT  provides  layered  software  to  provide  a  data  transfer  method  in  distributed  environments. 
While  RdT  minimizes  some  of  the  housekeeping,  it  naturally  introduces  some  overhead.  The 
actual  wall  clock  transfer  time  varies  with  machine  load  on  the  local  and  remote  machines  as  well 
as  the  network  traffic  at  a  given  time. 

Typical  transfer  times  between  two  Sun  4  machines  on  a  reasonably  loaded  network  result 
in  transfers  of  10,000  floats  in  about  0.1  s  or  in  the  neighborhood  of  1/3  to  1/2  MB/s.  Raw  TCP/IP 
packets  result  in  transfer  of  less  than  1  MB/s.  These  times  are  not  directly  comparable,  but  are 
useful  when  designing  a  distributed  application  where  such  transfer  times  may  or  may  not  be 
significant.  It  is  important  to  mention  that  transfer  times  do  not  vary  linearly.  The  RPC/XDR 
overhead  to  transfer  1 0  numbers  is  similar  to  that  of  transferring  1 ,000.  So  transferring  larger 
arrays  produces  better  than  average  throughput  than  the  transfer  of  small  arrays.  This  is 
generally  true  until  the  size  of  the  array  and  RdT  overhead  approach  the  size  of  physical  memory, 
where  the  allocation  of  memory  and  swapping  introduce  significant  overhead. 

RdT  has  been  used  to  distribute  the  sepau'ate  functions  of  an  application  across  several 
platforms.  Each  function  can  then  take  advantage  of  a  particular  architecture  or  set  of  resources. 
To  take  full  advantage  of  a  distributed  environment,  however,  RdT  could  use  some  additional 
flexibility.  Future  enhancements  include  additional  data  transport  mechanisms  such  as  shared 
memory.  The  message  passing  iayer  can  then  choose  the  most  appropriate  method  for  data 
transport.  For  example,  if  data  is  being  requested  from  the  local  host,  shared  memory  or  direct 
subroutine  calls  would  be  selected  to  implement  the  Command  and  Response  Layer.  In  addition, 
the  message  passing  iayer  will  be  made  more  flexible  to  help  implement  non-blocking  and 
intermediate  message  passing  where  a  message  is  passed  through  several  Servers  to  reach  its 
destination  or  is  broadcast  to  many  targets. 
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APPENDIX: 

RdT  USER  ROUTINES 
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RTU  CALL0C3R 


RTU  CALLOC  3R 


NAME 

rtujcalloc  •  Allocate  memory 
SYNTAX 

#include  <rtrpc.h> 

char  *rtu_calloc(num_elements.  elementjsize) 
int  num_elements: 
int  element_size; 


PARAMETERS 

num  elements  is  the  number  of  element  for  which  to  allocate  memory. 
element  size  is  the  number  of  bytes  in  eac^  element. 

DESCRIPTION 

Rtu  calloc  will  allocate  num  elements  *  element  size  bytes  of  memory;  possibly  by 
calling  callocO.  A  pointer  to  this  space  is  maintained  in  an  internal  list.  The  entire  internal 
list  of  allocated  memory  is  freed  on  the  next  call  to  rtu  cfree. 

SPECIAL  CONSIDERATIONS 

Rtu  calloc  may  not  always  use  calloc  to  allocate  memory  depending  on  the  architecture. 
DIAGNOSTICS 

Rtu  calloc  returns  a  pointer  to  the  memory  that  has  been  allocated  or  NULL  if  there  was 
an  error. 


SEE  ALSO 

rtu_poll(3R),  rtu_call(3R),  rtu_cfree(3R) 
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RTU_CFREE3R  RTU  CFREE  3R 


NAME 

rtu_cfree  -  free  memory 
SYNTAX 

#indude  <rtrpc.h> 
void  rtu_cfree() 

PARAMETERS 

none 

DESCRIPTION 

Rtu  cfree  frees  all  of  the  memory  that  has  been  allocated  using  rtu  calloc. 

SPECIAL  CONSIDERATIONS 

Rtu  cfree  usually  calls  cfree. 

DIAGNOSTICS 

Rtu  cfree  returns  no  value. 

SEE  ALSO 

rtu_poll(3R),  rtu_call(3R),  rtu_calloc(3R) 
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RTU  CALL3R 


RTU  CALL3R 


NAME 

rtu_call  -  call  an  RdT  server 
SYNTAX 

findude  <rtrpc.h> 

Int  rtu_call(rt_argc,  rt_argv.  hostname, 

sen/ice_id,  procedure.  user_data,  timeout); 
int  rt_argc,  servicejd,  timeout; 

RT_VAR  M.argvQ; 

char  *hostname.  *user_data.  'procedure; 

PARAMETERS 

Rt  arqc  defines  the  number  of  RT  VAR  pointers  in  the  array  rt  argv. 

rt  arav  is  an  array  of  pointers  to  RT  VAR  data  structures. 

hostname  is  the  hostname  of  the  RdT  server  to  be  called. 

service  id  is  the  number  of  the  service  that  is  requested. 

procedure  is  the  name  of  the  particular  function  inside  the  requested  service. 

user  data  is  a  user  defined  string  that  is  passed  to  the  server.  It  is  usually  used  as  an 
authentication. 

timeout  is  the  number  of  seconds  to  allow  for  a  response  from  the  sen/er. 
DESCRIPTION 

A  RT  VAR,  defined  in  rtrpc.h.  and  usually  built  bvrtu  make  var.  is  the  basic  data  structure 
used  by  RdT.  A  RT  VAR  must  be  one  of  the  following  types 

fdefine  TYPE.UNDEF  0 

#define  TYPE_BYTE  1 

#deflne  TYPE_SHORT  2 

#define  TYPE.LONG  3 

#define  TYPE.FLOAT  4 

#define  TYPE.DOUBLE  5 

#define  TYPE_COMPLEX  6 

#define  TYPE_STRING  7 

#define  TYPE  STRUCT  8 
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RTU  CALL3R 


RTU  CALL3R 


If  the  parameter  is  an  array  of  one  of  these  types,  it  is  ORed  with: 

#define  TYPE_ARRAY  0  x  80  /*  Compound  type  */ 

Rtu  call  passes  a  list  of  RT  VARs  to  a  RdT  server  running  on  the  machine  hostname  that 
has  registered  the  service  id. 

The  NULL  terminated  strings  user  data  and  procedure  are  also  passed  to  the  server. 
Procedure  is  intended  to  identify  the  function  inside  the  server  that  is  requested,  user  data 
is  intended  to  be  used  as  an  authentication  agreed  upon  by  the  client  and  server.  The 
actual  use  of  procedure  and  user  data,  however,  is  entirely  implementation  specific. 

Once  the  call  is  made,  the  client  will  be  blocked  for  timeout  seconds,  or  until  a 
response  is  received  from  the  server.  A  negative  time  out  causes  the  client  to  block,  while 
a  zero  time  out  returns  immediatly. 

SPECIAL  CONSIDERATIONS 

•  A  Server  must  always  respond  to  a  client  since  the  client  is  blocked  until  a  reply  is 
received. 

•  If  hostname  is  NULL,  then  the  local  host  is  used. 

•  user  data  and  procedure  may  also  be  NULL 
DIAGNOSTICS 

Rtu  call  always  returns  a  RT  VAR.  If  an  error  occurred,  the  type  of  the  RT  VAR  is  set 
to  TYPE_ERROR.  If  successful,  the  RT  VAR  returned  is  the  RT  VAR  that  was  passed 
by  the  server  to  the  routine  rtu  reply. 

SEE  ALSO 

rtu_reg(3R),  rtu_reply(3R),  rtu_poll(3R),  rtujet j)ar(3R),  rtu_calloc(3R)  rtu_cfree(3R), 
rtu_smpl_reply(3R) 
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RTU  GET  CMD  3R 


RTU  GET  CMD  3R 


NAME 

rtujgetjcmd  -  Retrieve  a  RdT  COMMAND  PACKET 


SYNTAX 

#include  <ilu_utiLh> 

COMMAND_PACKET  *rtu_get_cmd(service_number) 
Int  service_number; 


PARAMETERS 

Service  number  identifies  the  service  that  is  being  performed  by  the  server  on  behalf  of 
the  client. 


DESCRIPTION 

Rtu  get  cmd  implements  the  server  side  of  the  Command  and  Response  layer  (CRL)  of 
RdT.  CRL  is  based  upon  three  basic  data  structures: 

typedef  struct  { 

unsigned  char  type;  T  Basic  RdT  data  type  */ 
int  num_values;  /*  Number  of  elements  V 

char  *data;  r  Pointer  to  Data  */ 

}  PARAM.LIST; 


typedef  struct  { 

int  opcode;  T  Function  request  V 

int  num _param;  /*  Number  of  parameters  V 

PARAM_LIST  *params;  /*  Pointers  to  parameters  7 
}  COMMAND_PACKET; 


typedef  struct  { 
int 
char 
int 

PARAM  LIST 


}  RETURN_PACKET; 


status;  r  Status  of  command  7 
'explain;  /*  Explanation  of  Bad  status  7 
num_retum;  T  Number  of  returned  variables  */ 
'params;  /*  Pointers  to  return  parameters  7 


Rtu  get  cmd  retrieves  a  COMMAND_PACKET  from  a  client  program.  Some  function  is 
performed  by  the  server  and  a  RETURN_PACKET  is  passed  back  to  the  client. 


The  macro  SET_PARAM()  can  be  used  to  pack  data  into  a  RETURN_PACKET: 
SET_PARAM(RETURN_PACKET  packet,  int  which_param.  unsigned  char  type,  int 
array_size,  char  'data) 
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SPECIAL  CONSIDERATIONS 

•  A  Server  must  always  respond  to  a  client  since  the  client  is  blocked  until  a  reply  is 
received. 

DIAGNOSTICS 

Rtu  get  cmd  returns  NULL  on  an  error  after  printing  an  explanatory  message  to  stderr. 
If  successful,  rtu  get  cmd  returns  a  pointer  to  the  COMMAND_PACKET  that  was  sent  by 
the  client  to  the  server. 

SEE  ALSO 

rtu_reg(3R),  rtu_call(3R),  rtu_poll(3R),  rtu_get_par(3R),  rtu_calloc(3R)  rtu_cfree(3R), 
rtu_smpl_reply(3R),  rtu_s_cmd(3R),  rtu_reply(3R) 
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NAME 

rtu_get_par  -  Retrieve  RdT  parameters 
SYNTAX 

#include  <rtrpc.h> 

char  *  rtu_get_par(parameter_number,  expected_type) 

intparameter_number; 

unsigned  char  expected_type; 

PARAMETERS 

parameter  number  specifies  which  parsuneter  (numbered  from  0)  is  to  be  retrieved. 

expected  type  specifies  the  type  of  the  parameter  that  is  expected.  Expected  type  is  one 
of  the  rt  var  types  defined  in  rtrpc.h: 

#define  TYPE_UNDEF  0 

#define  TYPE_BYTE  1 

#define  TYPE_SHORT  2 

#define  TYPE_LONG  3 

#define  TYPE_FLOAT  4 

#define  TYPE.DOUBLE  5 

#define  TYPE.COMPLEX  6 

#deflne  TYPE_STRING  7 

#define  TYPE_STRUCT  8 

If  the  parameter  is  an  array  of  one  of  these  types,  it  is  ORed  with: 

#define  TYPE_ARRAY  0  x  80  T  Compound  type  V 
DESCRIPTION 

Rtu  get  par  returns  a  pointer  to  the  data  of  the  requested  parameter.  The  return  pointer 
from  rtu  get  par  must  be  cast  to  the  proper  type.  For  example,  if  the  first  expected 
parameter  was  an  array  of  floats,  the  call  would  be: 

float  'first jaaram; 

first_param  =  (float  *)rtujget_par(0, 

TYPE_FLOAT  |  TYPE.ARRAY); 

If  rtu  get  par  was  successful  in  retrieving  the  first  parameter,  the  data  is  pointed  to  by  the 
pointer  first_j>aram. 
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SPECIAL  CONSIDERATIONS 

•  The  expected  type  of  the  parameter  must  match  exactly. 

•  The  data  pointed  to  by  rtu  get  oar  has  been  allocated  using  rtu  calloc.  That  storage 
space  will  be  freed  on  the  next  call  to  rtu  reolv.  So  the  data  must  be  copied  before  a 
response  is  made  or  the  data  will  be  corrupted. 

DIAGNOSTICS 

Rtu  get  par  returns  NULL  if  the  expected  type  does  not  match  the  parameter  or  if  there 
are  less  parameters  than  the  number  ttiat  was  requested  with  parameter  number. 
Otherwise,  rtu  get  par  returns  a  pointer  to  the  data. 

SEE  ALSO 

rtu_reg(3R),  rtu_call{3R),  rtuj30ll(3R).  rtu_reply(3R),  rtu_calloc(3R)  rtu_cfree(3R) 
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NAME 

rtu_make_structure  -  build  an  RT_VAR 
SYNTAX 

finclude  <rtrpc.h> 

int  rtu_make_structure(c_structure_ptr, 
type,  length, 


b) 


char  *c_structurejDtr; 
unsigned  char  type; 
unsigned  long  length; 

PARAMETERS 

C  structure  otr  is  a  pointer  to  an  a  ’C’  structure. 

Type  is  the  RT_VAR  type  of  the  data  of  the  RT  VAR  to  be  built. 

Length  is  the  number  of  elements  in  the  array  pointed  to  by  associated  ’C’  structure 
element  or  1  if  the  element  is  a  scaler. 

DESCRIPTION 

Rtu  make  structure  builds  an  RT  VAR  of  type  TYPE  STRUCT  from  the  data  pointed  to 
by  c  structure  ptr. 

Rtu  make  structure  uses  a  yariable  argument  list  terminated  by  a  0.  This  allows  an 
arbitrary  sized  'C  structure  to  be  passed  and  defined.  There  must  be  one  type,  length  pair 
for  each  element  of  the  structure. 


Type  must  be  one  of  the  rt  yar  types  defined  in  rtrpc.h: 


#define 

#define 

fdefine 

#define 

#define 

#define 

#define 

#define 

fdefine 


TYPE 

TYPE 

TYPE 

TYPE 

TYF 

TYi-^ 

TYPE 

TYPE 

TYPE 


UNDER 

BYTE 

SHORT 

LONG 

FLOAT 

DOUBLE 

COMPLEX 

STRING 

STRUCT 


0 

1 

2 

3 

4 

5 

6 

7 

8 
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If  the  parameter  is  an  array  of  one  of  these  types,  it  is  ORed  with: 

#define  TYPE_ARRAY  0  x  80  /*  Compound  type  V 
SPECIAL  CONSIDERATIONS 

•  Rtu  make  structure  allocates  the  RT  VAR  that  is  returned  with  rtu  calloc.  This  will  be 
freed  on  the  next  call  to  rtu  call  or  rtu  reply. 

DIAGNOSTICS 

Rtu  make  structure  returns  an  pointer  to  a  RT  VAR  or  I4ULL  if  the  was  an  error. 

SEE  ALSO 

rtu_reg(3R),  rtu_cail(3R),  rtujx)ll(3R),  rtujget_par(3R),  rtu_calloc(3R)  rtu_cfree(3R), 
rtu_reply(3R),  rtu_smpl_reply(3R) 
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NAME 

rtu_make_var  -  build  a  RT_VAR 

SYNTAX 

#include  <rtrpG.h> 

int  rtu_make_var(rt_var_ptr,  type, 

length,  data_pointer) 

RT_VAR  *rt_var_ptr; 
unsigned  char  type; 
unsigned  long  length; 
char  *dataj3ointer; 

PARAMETERS 

rt  var  ptr  is  a  pointer  to  a  RT  VAR  data  structure  defined  in  rtroc-h. 

Type  is  the  RT_VAR  type  of  the  data  of  ttie  RT  VAR  to  be  built. 

Length  is  the  number  of  elements  in  the  array  pointed  to  by  data  pointer,  or  1  if  the  data 
is  a  scaler. 

DESCRIPTION 

Rtu  make  var  builds  a  RT  VAR  from  the  supplied  information  and  places  the  variable  in 
the  RT  VAR  pointed  to  by  rt  var  ptr.  Type  must  be  one  of  the  rt  var  types  defined  in 
rtrpc.h: 

#define  TYPE_UNDEF  0 

#define  TYPE_BYTE  1 

#define  TYPE_SHORT  2 

#define  TYPE_LONG  3 

#define  TYPE_FLOAT  4 

#define  TYPE_DOUBLE  5 

#define  TYPE_COMPLEX  6 

fdefine  TYPE_STRING  7 

#define  TYPE_STRUCT  8 

If  the  parameter  is  an  array  of  one  of  these  types,  it  is  ORed  with: 

#define  TYPE_ARRAY  0  x  80  T  Compound  type  V 

SPECIAL  CONSIDERATIONS 

•  rt  var  Ptr  must  point  to  a  RT  VAR:  the  RT  VAR  is  not  allocated  by  rtu  make  var. 

DIAGNOSTICS 

Rtu  make  var  returns  1  on  success  0  on  failure. 
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SEE  ALSO 

rtu_reg(3R),  rtu_call(3R),  rtu _poll(3R),  rtujget_par(3R),  rtu_calIoc(3R)  rtu_cfree(3R), 
rtu_reply(3R),  rtu_smpl_reply(3R) 
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NAME 

rtu _poll  -  listen  for  a  RdT  service  request 
SYNTAX 

#include  <rtrpc.h> 

int  rtu_poll(user_data,  procedure,  blockjime) 
char  ,**user_data; 
char  *‘*procedure; 
int  block_time; 

PARAMETERS 

user  data  points  to  a  character  string  of  user  specific  data.  This  is  usualiy  used  as  some 
type  of  access  authorization  but  can  be  used  to  pass  any  character  string. 

procedure  points  to  a  character  string  that  usualiy  specifies  the  name  of  the  procedure 
within  the  requested  service  that  the  client  program  desires.  Again  this  is  the  intended 
use.  but  the  client  is  free  to  pass  any  information  in  this  string. 

block  time  specifies  the  type  and  length-  of  blocking.  If  block  time  is  negative,  rtu  poii 
does  not  return  until  a  service  request  is  received  from  a  client.  If  block  time  is  zero. 
rtu  poll  checks  for  an  incoming  service  request  and  returns  immediately.  Any  other  value 
is  taken  as  the  amount  of  seconds  to  block  for  an  incoming  service  request  before 
returning. 

DESCRIPTION 

Rtu  poll  listens  for  a  request  of  a  RdT  service  that  has  been  previously  registered  with 
rtu  reo.  When  a  request  is  received,  the  user  data  and  procedure  values  are  read  from 
the  client  and  stored  in  a  storage  area  that  is  pointed  to  by  user  data  and  procedure. 
When  a  valid  request  has  been  received,  the  parameters  passed  from  the  client  are 
retrieved  with  rtu  oet  par.  The  server  generaily  checks  the  data  in  user  data  to  assure 
that  the  client  is  authorized  to  make  the  request,  then  passes  all  parameters  to  the 
particular  function  specified  by  procedure. 

SPECIAL  CONSIDERATIONS 

•  rtu  poll  must  be  called  after  rtu  reo. 

DIAGNOSTICS 

Rtu  poll  returns  1  if  a  vaiid  request  has  been  received  or  0  if  no  service  request  has  been 
received. 

SEE  ALSO 

rtu_reg(3R),  rtu_call(3R),  rtu_get_par(3R),  rtu_reply(3R) 
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NAME 

rtu_reg  -  register  a  RdT  service 
SYNTAX 

#inciucle  <rtrpc.h> 

int  rtu_reg(service_number) 

int  service_number 

PARAMETERS 

service  number  a  unique  number  identifying  the  sen/ice 
DESCRiPTION 

Rtu  rea  registers  a  RdT  service  uniqueiy  identified  by  sen/ice  number.  A  client  process 
requesting  service  number  will  be  served  by  this  service. 

SPECIAL  CONSIDERATIONS 

•  Rtu  rea  overrides  an  previous  call.  Any  senrice  that  has  been  previously  registered 
with  the  same  service  number  is  unreachable. 

DIAGNOSTICS 

Rtu  rea  returns  1  if  the  service  was  registers  successfully  or  0  on  an  error. 

SEE  ALSO 

rtu_poll(3R),  rtu_call(3R) 
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NAME 

rtu_rep!y  -  reply  to  an  RdT  client 
SYNTAX 

findude  <rtrpc.h> 

int  rtu_reply(service_number.  reply_method,  reply) 

Int  servlce_number; 
int  reply_method; 

RT_VAR  *reply; 

PARAMETERS 

Service  number  identifies  the  service  that  was  specified  with  rtu  reo  that  is  being 
performed  on  behalf  of  the  client. 

Reply  method  specifies  if  the  passed  parameters  are  returned  to  the  client  along  with  the 
reply. 

reply  is  the  actual  reply  data  sent  to  the  client  reply  must  be  one  of  the  rt  var  types 
defined  in  rtrpc.h: 

#defineTYPE  UNDER  0 
#define  TYPE.BYTE  1 

#define  TYPE_SHORT  2 

#define  TYPE.LONG  3 

#deflne  TYPE_FLOAT  4 

#deflne  TYPE_DOUBLE  5 

#deflne  TYPE_COMPLEX  6 

#define  TYPE_STRING  7 

fdefine  TYPE_STRUCT  8 

If  the  parameter  is  an  array  of  one  of  these  types,  it  is  ORed  with: 

#define  TYPE_ARRAY  0  x  80  T  Compound  type  V 
DESCRIPTION 

Rtu  reply  is  the  most  general  return  routine  in  the  RdT  package.  For  simple  replies  of 
scalars  and  arrays,  rtu  smpi  repIvO  is  usually  sufficient. 

Rtu  reply  sends  the  data  specified  in  reply  back  to  the  RdT  client  in  response  to  a  service 
request  If  reply  method  is  RETURN_PARAMS,  the  parameters  passed  to  the  server  from 
rtu  get  par,  are  returned  to  the  client  This  allows  the  server  to  change  the  data  in  a 
parameter  and  return  it  to  a  client  without  the  need  to  allocate  new  memory.  If 
reply  method  is  set  to  REPLY_ONLY  no  parameters  are  returned.  This  is  faster  than 
returning  all  parameters. 
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SPECIAL  CONSIDERATIONS 

•  A  Server  must  always  respond  to  a  client  since  the  client  is  biocked  untii  a  repiy  is 
received. 

DIAGNOSTICS 

Rtu  reply  returns  1  on  success  0  on  failure. 

SEE  ALSO 

rtu_reg(3R),  rtu_call(3R),  rtu_poll(3R),  rtujget_par{3R),  rtu_calloc(3R)  rtu_cfree(3R), 
rtu_smpl_reply(3R) 
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NAME 

rtu_retum  -  respond  to  a  RdT  client 
SYNTAX 

#inciude  <rtu_util.h> 

int  rtu_retum(retum_packet) 

RETURN_PACKET  *retum_packet; 


PARAMETERS 

Return  packet  is  the  data  structure  that  contains  the  response  to  the  client. 


DESCRIPTION 

Rtu  return  helps  implement  the  server  side  of  the  Command  and  Response  Layer  (CRL) 
of  RdT.  CRL  is  based  upon  three  basic  data  structures: 


typedef  struct  { 
unsigned  char 
int 
char 

}  PARAM_LIST; 


type;  /*  Basic  RdT  data  type  7 
num_values;  r  Number  of  elements  7 
•data;  /*  Pointer  to  Data  7 


typedef  struct  { 

int  opcode;  /*  Function  request  7 

int  num_param;  /*  Number  of  parameters  */ 

PARAM_LIST  *params;  /*  Pointers  to  parameters  7 
}  COMMAND_PACKET; 


typedef  struct  { 
int 
char 
int 

PARAM  LIST 


}  RETURN_PACKET; 


status;  r  Status  of  command  7 
•explain;  /•  Explanation  of  Bad  status  7 
num_retum;  T  Number  of  returned  variables  •/ 
•params;  T  Pointers  to  return  parameters  •/ 


Rtu  return  returns  the  RETURN_PACKET  to  the  client  in  response  to  some  request  for 
service.  The  macro  SET_PARAM()  can  be  used  to  pack  data  into  a  RETURN_PACKET: 

SET_PARAM(RETURN_PACKET  packet,  int  whichjjaram, 

unsigned  char  type, 

int  array.size,  char  •data) 
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SPECIAL  CONSIDERATIONS 

•  A  Server  must  always  respond  to  a  client  since  the  client  is  blocked  until  a  reply  is 
received. 

DIAGNOSTICS 

Rtu  return  returns  1  on  success  0  on  failure. 

SEE  ALSO 

rtu_reg(3R),  rtu_call(3R),  rtu _poll(3R),  rtu_getj3ar(3R),  rtu_calloc(3R)  rtu_cfree(3R), 
rtu_smpl_reply(3R),  rtu_s_cmd(3R),  rtu_reply(3R) 
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NAME 

rtu_send_cmd  -  Send  a  RdT  COMMAND  PACKET 
SYNTAX 

#include  <rtu_util.h> 

char  *rtu_send_cmd(hostname,  setvice_number, 
command_packet) 
char  *hostnanie; 
int  service_number; 

COMMAND_PACKET  *command_packet; 

PARAMETERS 

Hostname  is  the  name  of  the  host  that  is  executing  the  Server  side  of  RdT. 

Service  number  identifies  the  service  that  was  specified  with  rtu  reo  that  is  being 
performed  on  behalf  of  the  client. 

Command  packet  points  to  a  valid  COMMAND_PACKET, 

DESCRIPTION 

Rtu  send  cmd  implements  the  client  side  of  the  Command  and  Response  layer  (CRL)  of 
RdT.  CRL  is  based  upon  three  basic  data  structures; 

typedef  struct  { 

unsigned  char  type;  /*  Basic  RdT  data  type  */ 
int  num_values;  /*  Number  of  elements  V 

char  *datay*  Pointer  to  Data  V 

}  PARAM_LIST; 

typedef  struct  { 

int  opcode;  r  Function  request  */ 

int  num_param;  /*  Number  of  parameters  */ 

PARAM_LIST  *params;  /*  Pointers  to  parameters  V 
}  COMMAND_PACKET; 

typedef  struct  { 

int  status;  r  Status  of  command  */ 

char  'explain;  r  Explanation  of  Bad  status  V 

int  num_retum;  r  Number  of  returned  variables  */ 

PARAM_LIST  'params;  /*  Pointers  to  return  parameters  7 
}  RETURN_PACKET; 
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Rtu  send  cmd  sends  a  COMMAND_PACKET  to  a  server  program  running  on  hostname 
that  has  been  registered  with  service  number.  When  the  server  responds  with  a 
RETURN_PACKET,  a  pointer  to  the  data  element  of  the  structure  is  returned  as  a  result 
of  rtu  send  cmd. 

The  macros  SELECT  COMMANDf)  and  SET  PARAMO  are  usually  called  to  build  the 
COMMAND_PACKET: 

SELECT_COMMAND(COMMAND_PACKET  packet,  int  opcode, 

Int  number_of jjarameters) 

SET_PARAM(COMMAND_PACKET  packet,  int  which_param, 
unsigned  char  type, 

Int  array_size,  char  *data) 

SPECIAL  CONSIDERATIONS 

•  A  Server  must  always  respond  to  a  client  since  the  client  is  blocked  until  a  reply  is 
received. 

DIAGNOSTICS 

Rtu  send  cmd  returns  NULL  on  an  error  after  printing  an  explanatory  message  to  stderr. 
If  successful,  rtu  send  cmd  returns  a  pointer  to  the  data  that  was  returned  as  a  result  from 
the  server. 

SEE  ALSO 

rtu_reg(3R),  rtu_call(3R),  rtujX)ll(3R),  rtu_get _par(3R),  rtu_calloc(3R)  rtu_cfree(3R), 
rtu_smpl_reply(3R),  rtu_get_cmd(3R) 


Reference  Manual 


Subroutines 


44 


RTU  SMPL  REPLY  3R 


NAME 

rtu_smpl_reply  -  reply  to  a  RdT  client 

SYNTAX 

findude  <rtrpc.h> 

int  rtu_smpl_reply(type.  length.  datajDointer) 
unsigned  char  type; 
unsigned  long  length; 
char  *data_pointer; 

PARAMETERS 

Type  is  the  RT_VAR  type  of  the  reply  data  sent  to  the  client.  Type  must  be  one  of  the 
rt  yar  types  defined  in  rtroc.h: 

#define  TYPE_UNDEF  0 

#define  TYPE_BYTE  1 

#define  TYPE_SHORT  2 

#define  TYPE_LONG  3 

#defineTYPE  FLOAT  4 
fdefine  TYPE_DOUBLE  5 

fdefine  TYPE  COMPLEX  6 

#define  TYPE.STRING  7 

#define  TYPE_STRUCT  8 

If  the  parameter  is  an  array  of  one  of  these  types,  it  is  ORed  with: 

#define  TYPE_ARRAY  0  x  80  /*  Compound  type  7 

Length  is  the  number  of  elements  in  the  array  pointed  to  by  data  pointer,  or  1  if  the  data 
is  a  scaler. 

DESCRIPTION 

Rtu  smpi  reply  builds  a  RT_VAR  from  the  information  supplied  and  passes  it  to  rtu  repiy 
to  be  passed  back  to  a  RdT  client.  Only  the  data  pointed  to  by  data  pointer  is  returned 
to  the  client;  no  parameters  are  returned. 

SPECIAL  CONSIDERATIONS 

•  A  Seryer  must  always  respond  to  a  client  since  the  client  is  blocked  until  a  reply  is 

received. 

DIAGNOSTICS 

Rtu  reply  returns  1  on  success  0  on  failure. 
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SEE  ALSO 

rtu_reg(3R),  rtu_call(3R),  rtu_poll(3R),  rtu_get_par(3R),  rtu_calloc(3R)  rtu_cfree(3R), 
rtu_reply(3R) 
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1 
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Director 
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Development,  and  Engineering  Center 
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2 

Commander 
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